#region Copyright and License Notice
// Copyright (C)2010-2016 - Rob Levine and other contributors
// http://configgen.codeplex.com
// 
// This file is part of ConfigGen.
// 
// ConfigGen is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// ConfigGen is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License and 
// the GNU Lesser General Public License along with ConfigGen.  
// If not, see <http://www.gnu.org/licenses/>
#endregion

using System;
using System.Collections.Generic;

namespace ConfigGen.Core.ConfigurationSettings
{
    /// <summary>
    /// Interface implemented by <see cref="ConfigurationExpressionEvaluator"/>. <see cref="PrepareExpression"/> should be called first,
    /// followed by <see cref="Evaluate"/>.
    /// </summary>
    public interface IConfigurationExpressionEvaluator
    {
        /// <summary>
        /// Prepares the supplied expression for evaluation by removing the "$" symbol prefix from tokens in the expression, and
        /// returns a list of all tokens found in the expression
        /// </summary>
        /// <param name="expression">Expression to prepare.</param>
        /// <returns>List of tokens in the supplied expressions.</returns>
        /// <exception cref="ArgumentNullException">Thrown if <paramref name="expression"/> is null</exception>
        /// <exception cref="ArgumentException">Thrown if <paramref name="expression"/> is zero length</exception>
        IEnumerable<string> PrepareExpression(ref string expression);

        /// <summary>
        /// Returns true if the supplied expression evaluates to a configuration setting for the specified machine, otherwise false.
        /// If the machine does not exist, false is returned.
        /// </summary>
        /// <remarks>
        /// <ul>
        /// <li>To return true if a token "t1" is specified for machine "machine1": <code>Evalute("machine1", "t1")</code> or <code>Evalute("machine1", exists("t1"))</code></li>
        /// <li>To return true if a token "t1" has the value 123 for machine "machine1": <code>Evalute("machine1", "t1=123")</code></li> 
        /// <li>To return true if a token "t1" has the value "ABC" for machine "machine1": <code>Evalute("machine1", "t1='ABC'")</code></li> 
        /// <li>To return true if a token "t1" has a value greater than 12 for machine "machine1": <code>Evalute("machine1", "t1>12")</code></li> 
        /// </ul>
        /// </remarks>
        /// <param name="machineName">The machine name.</param>
        /// <param name="expression">Serach expression.</param>
        /// <returns>true if the supplied expression evaluates to a configuration setting for the specified machine, otherwise false</returns>
        /// <exception cref="ArgumentNullException">Thrown if either argument is null</exception>
        /// <exception cref="ArgumentException">Thrown if either argument is zero length</exception>
        bool Evaluate(string machineName, string expression);

        /// <summary>
        /// Gets the underlying collection of machine's settings
        /// </summary>
        /// <value>The machine settings collection.</value>
        MachinesConfigurationCollection MachinesConfigurationCollection { get; }
    }
}